<html>
<head>
<title>Status File for Jakarta Commons "Collections" Package</title>
<head>
<body bgcolor="white">


<div align="center">
<h1>The Jakarta Commons <em>Collections</em> Package</h1>
$Id: STATUS.html,v 1.19 2002/10/21 02:03:29 bayard Exp $<br>
<a href="#Introduction">[Introduction]</a>
<a href="#Dependencies">[Dependencies]</a>
<a href="#Release Info">[Release Info]</a>
<a href="#Committers">[Committers]</a>
<a href="#Action Items">[Action Items]</a>
<br><br>
</div>


<a name="Introduction"></a>
<h3>1.  INTRODUCTION</h3>

<p>The <em>Collections</em> package contains a set of Java classes that
extend or augment the Java Collections Framework.
The following classes are included:</p>
<ul>
<li><strong>ArrayStack</strong> - An implementation of the java.util.Stack API
    that is based on an ArrayList instead of a Vector, so it is not synchronized to
    protect against multi-threaded access.</li>
<li><strong>Bag</strong> - A Collection that keeps a count of its members of the same
    type, using <code>hashCode</code> to check for equality. Suppose
    you have a Bag that contains <code>{a, a, b, c}</code>.  Calling
    getCount on <code>a</code> would return 2, while calling
    uniqueSet would return <code>{a, b, c}</code>.  <i>Note: this is an
    interface with several implementations.</i></li>
<li><strong>BagUtils</strong> - Provides utility methods and decorators 
    for Bag and SortedBag instances.</li>
<li><strong>BeanMap</strong> - An implementation of the java.util.Map API
    that is based on a JavaBean using introspection. The property names are the
    keys of the map and the property values are the values of the map.</li>
<li><strong>BinaryHeap</strong> - Binary heap implementation 
    of PriorityQueue and Buffer.</li>
<li><strong>BoundedFifoBuffer</strong> - a very efficient implementation of 
    Buffer that does not alter the size of the buffer at runtime.</li>
<li><strong>Buffer</strong> - a collection that allows objects to be removed 
    in some well-defined order.</li>
<li><strong>BufferUtils</strong> - Contains static utility methods for 
    buffers.</li>
<li><strong>CollectionUtils</strong> - a variety of helper methods
    for working with collections.</li>
<li><strong>ComparatorUtils</strong> - Contains static utility methods for
    comparators.</li>
<li><strong>CursorableLinkedList</strong> - an implementation of the java.util.List
    interface supporting a java.util.ListIterator that allows concurrent
    modifications to the underlying list.</li>
<li><strong>DoubleOrderedMap</strong> - Red-Black tree-based implementation of Map. 
    This class guarantees
    that the map will be in both ascending key order and ascending
    value order, sorted according to the natural order for the key's
    and value's classes.</li>
<li><strong>ExtendedProperties</strong> - extends normal Java properties by adding
    the possibility to use the same key many times, concatenating the value strings
    instead of overwriting them.</li>
<li><strong>FastArrayList</strong> - a custom implementation of java.util.ArrayList
    designed to operate in a multithreaded environment where the large majority of
    method calls are read-only, instead of structural changes.</li>
<li><strong>FastHashMap</strong> - a custom implementation of java.util.HashMap
    designed to operate in a multithreaded environment where the large majority of
    method calls are read-only, instead of structural changes.</li>
<li><strong>FastTreeMap</strong> - a custom implementation of java.util.TreeMap
    designed to operate in a multithreaded environment where the large majority of
    method calls are read-only, instead of structural changes.</li>
<li><strong>HashBag</strong> -  An implementation of <strong>Bag</strong> that is backed by a 
    HashMap.</li>
<li><strong>IteratorUtils</strong> - Contains static utility methods for
    iterators.</li>
<li><strong>ListUtils</strong> - miscelaneous utilities to manipulate Lists.</li>
<li><strong>MultiMap</strong> - This is simply a Map with slightly different semantics.
    Instead of returning an Object, it returns a Collection.
    So for example, you can put( key, new Integer(1) ); 
    and then a Object get( key ); will return you a Collection 
    instead of an Integer.  This is an interface implemented
    by <strong>MultiHashMap</strong>.</li>
<li><strong>PriorityQueue</strong> - a PriorityQueue interface, with
    <strong>BinaryHeap</strong> and <strong>SynchronizedPriorityQueue</strong>
    implementations.</li>
<li><strong>ProxyMap</strong> - This <code>Map</code> wraps another <code>Map</code>
    implementation, using the wrapped instance for its default
    implementation.  This class is used as a framework on which to
    build to extensions for its wrapped <code>Map</code> object which
    would be unavailable or inconvenient via sub-classing (but usable
    via composition).</li>
<li><strong>ReferenceMap</strong> - Hashtable-based Map implementation that 
    allows mappings to be removed by the garbage collector.</li>
<li><strong>SequencedHashMap</strong> -  A map of objects whose mapping entries are 
    sequenced based on the order in
    which they were added.</li>
<li><strong>SortedBag</strong> - A type of <strong>Bag</strong> that maintains order among its unique
    representative members</li>
<li><strong>StaticBucketMap</strong> - An efficient, thread-safe 
    implementation of java.util.Map that performs well in in a highly 
    thread-contentious environment.</li>
<li><strong>StringStack</strong> - A stack for string objects.</li>
<li><strong>SynchronizedPriorityQueue</strong> - A thread-safe version of
    the priority queue.</li>
<li><strong>TreeBag</strong> - An implementation of <strong>Bag</strong> that is backed by a 
    TreeMap. Order will be maintained among the unique representative
    members.</li>
<li><strong>UnboundedFifoBuffer</strong> - Efficient implementation of Buffer
    that alters the size of the buffer at runtime.</li>
</ul>

<p><b>comparators subpackage:</b></p>

<ul>
<li><strong>ComparableComparator</strong> - A Comparator that compares Comparable objects.
    This Comparator is useful, for example,
    for enforcing the natural order in custom implementations
    of SortedSet and SortedMap.</li>
<li><strong>ComparatorChain</strong> -  ComparatorChain is a Comparator that wraps one or
    more Comparators in sequence.  The ComparatorChain
    calls each Comparator in sequence until either 1)
    any single Comparator returns a non-zero result
   (and that result is then returned),
   or 2) the ComparatorChain is exhausted (and zero is
   returned).  This type of sorting is very similar
   to multi-column sorting in SQL, and this class
   allows Java classes to emulate that kind of behaviour
   when sorting a List.</li>
<li><strong>NullComparator</strong> - A comparator that will compare nulls
    to be either higher or lower than other objects.</li>
<li><strong>ReverseComparator</strong> - Reverses the order of another 
    comparator.</li>
<li><strong>TransformingComparator</strong> - Decorates another comparator
    with transformation behavior.</li>

</ul>

<p><b>iterators subpackage:</b></p>

<ul>
<li><strong>ArrayIterator</strong> - a java.util.Iterator wrapper for arrays.</li>
<li><strong>CollectinIterator</strong> - Provides an ordered iterator over
    the elements contained in a collection of ordered iterators.</li>
<li><strong>EnumerationIterator</strong> - Adapter to make Enumeration
    instances appear to be Iterator instances.</li>
<li><strong>FilterIterator</strong> - A Proxy <code>Iterator</code> which takes a 
    <code>Predicate</code> 
    instance to filter out objects from an underlying <code>Iterator</code> instance.
    Only objects for which the
    specified <code>Predicate</code> evaluates to <code>true</code> are
    returned.</li>
<li><strong>FilterListIterator</strong> - A proxy <code>ListIterator</code> which 
    takes a <code>Predicate</code> instance to filter
    out objects from an underlying <code>ListIterator</code> 
    instance. Only objects for which the specified 
    <code>Predicate</code> evaluates to <code>true</code> are
    returned by the iterator.</li>
<li><strong>IteratorChain</strong> - An iterator that wraps one or more 
    iterators.</li>
<li><strong>IteratorEnumeration</strong> - Adapter to make Iterator instances
    appear to be Enumeration instances.</li>
<li><strong>ListIteratorWrapper</strong> - As the wrapped Iterator is 
    traversed, ListIteratorWrapper builds a LinkedList of its values, 
    permitting all required operations of ListIterator.</li>
<li><strong>ProxyIterator</strong> - Delegates its methods to a proxy 
    instance.</li>
<li><strong>ProxyListIterator</strong> - Delegates its methods to a proxy 
    instance.</li>
<li><strong>SingletonIterator</strong> - An Iterator over a single 
    object instance.</li>
<li><strong>SingletonListIterator</strong> - A ListIterator over a single 
    object instance.</li>
<li><strong>TransformIterator</strong> - Uses a Transformer instance to 
    transform the contents of the Iterator into some other form.</li>
<li><strong>UniqueFilterIterator</strong> - A FilterIterator which only 
    returns "unique" Objects.</li>
</ul>

<a name="Dependencies"></a>
<h3>2.  DEPENDENCIES</h3>

<p>The <em>Collections</em> package is dependent upon the following external
components for development and use:</p>
<ul>
<li><a href="http://java.sun.com/j2se">Java Development Kit</a>
    (Version 1.2 or later)</li>
<li><a href="http://www.junit.org">JUnit Testing Framework</a>
    (Version 3.7 or later) - for unit tests only, not required
    for deployment</li>
</ul>


<a name="Release Info"></a>
<h3>3.  RELEASE INFO</h3>

<p>Current Release:
<a href="http://jakarta.apache.org/builds/jakarta-commons/release/commons-collections/v2.1">Version 2.1</a>

<p>Planned Next Release:  ?</p>

<a name="Committers"></a>
<h3>4.  COMMITTERS</h3>

<p>The following individuals are the primary developers and maintainers of this
component.  Developers who plan to use <em>Collections</em> in their own
projects are encouraged to collaborate on the future development of this
component to ensure that it continues to meet a variety of needs.</p>
<ul>
   <li><a href="mailto:mas@apache.org">Michael A. Smith</a></li>
   <li><a href="mailto:morgand@apache.org">Morgan Delagrange</a></li>
   <li><a href="mailto:donaldp@apache.org">Peter Donald</a></li>
   <li><a href="mailto:geirm@apache.org">Geir Magnusson Jr.</a></li>
   <li><a href="mailto:craigmcc@apache.org">Craig McClanahan</a></li>
   <li><a href="mailto:jstrachan@apache.org">James Strachan</a></li>
   <li><a href="mailto:rwaldhoff@apache.org">Rodney Waldhoff</a></li>
   <li><a href="mailto:jvanzyl@apache.org">Jason van Zyl</a></li>
   <li><a href="mailto:bayard@apache.org">Henri Yandell</a></li>
   <li><a href="mailto:pjack@apache.org">Paul Jack</a></li>
   <li><a href="mailto:scolebourne@apache.org">Stephen Colebourne</a></li>
</ul>

<a name="Action Items"></a>
<h3>5.  ACTION ITEMS</h3>

<p>Want to help?  Here's some "to do" items the team has identified.</p>

<table border="1">
  <tr>
    <th width="80%">Action Item</th>
    <th width="20%">Volunteer</th>
  </tr>

  <tr>
    <td><strong>Additional Contributions</strong>.  Other collection
    or collection-related classes or decorators.</td>
    <td align="center">&nbsp;</td>
  </tr>
  
  <tr>
    <td><strong>Primitive subpackage</strong>.  Complete implementations of
    a collections system based on primitives.</td>
    <td align="center">&nbsp;</td>
  </tr>
  
  <tr>
    <td><strong>MultiMap ideas</strong>.  Updates to MultiMap, maybe based on
	 <a href="http://www.innig.org/util/innig-util/build/javadoc">this library</a>.</td>
    <td align="center">&nbsp;</td>
  </tr>

  <tr>
    <td><strong>Additional Documentation</strong>.  Create simple
        User's Guide, examples, or other documentation for this package.</td>
    <td align="center">&nbsp;</td>
  </tr>

  <tr>
    <td><strong>Serializable Collections</strong>.  All of the concrete
        Collection and Map implementations should be properly Serializable
        across all versions of the JDK.  Also, decorators should be 
        Serializable if the underlying instance is.</td>
    <td align="center">&nbsp;</td>
  </tr>

  <tr>
    <td><strong>Fail-Fast Iterators</strong>.  All concrete Collection and
        Map implementations that can have fail-fast iterators should have
        them.  Some classes, like StaticBucketMap, cannot possibly have 
        fail-fast iterators, but otherwise everything else should.</td>
    <td align="center">&nbsp;</td>
  </tr>

  <tr>
    <td><strong>Standard Constructors</strong>.  All concrete Collection and
        Map implementations should have the standard copy and no-argument
        constructors.</td>
    <td align="center">&nbsp;</td>
  </tr>

  <tr>
    <td><strong>Additional Unit Tests</strong>.  Create generic unit tests
        for SortedSet and SortedMap.</td>
    <td align="center">&nbsp;</td>
  </tr>
    
</table>

</body>
</html>
